home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / dskut / p22v12.zip / PATCH22.DOC < prev    next >
Text File  |  1991-08-08  |  15KB  |  371 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                               PATCH22
  11.  
  12.  
  13.                      version 1.2  (8 August 1991)
  14.  
  15.                           Jurgen A. Doornik
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.     1. Introduction.
  26.     ___________________________________________________________________
  27.  
  28.     PATCH22 can be used to make patches to any file. The main
  29.     advantage is that it gives a format to distribute patches. You
  30.     can avoid detailed description of DEBUG commands. Instead you
  31.     just supply PATCH22 with the patch in a *.P22 file.
  32.     PATCH22 can also accept patches on the command line.
  33.     Patches have a C-like character constant format, making
  34.     it easy to enter hexadecimal values. PATCH22 will show the
  35.     context of the patch, but can work silently as well.
  36.     PATCH22 is written in C (source code provided), and faster than
  37.     many other public domain patch programs.
  38.     PATCH22 is written by Jurgen Doornik.
  39.  
  40.     The disk (or archive) should contain the following files:
  41.  
  42.        PATCH22.C     - source code (MSC 6.0)
  43.        PATCH22.DOC   - this documentation
  44.        PATCH22.EXE   - executable file.
  45.        *.P22         - patch files (if any).
  46.  
  47.     If you have any suggestions for improvement, or find any bugs,
  48.     please report them to me, via email:
  49.  
  50.        BITNET/EARN: ECONZ@UK.AC.OX.VAX
  51.  
  52.     or by mail:
  53.  
  54.     Jurgen Doornik
  55.     Institute of Economics and Statistics
  56.     St Cross Building, Manor Road
  57.     Oxford OX1 3UL
  58.     United Kingdom
  59.  
  60.     Special thanks are due to Arjen Merckens, who spotted many bugs and
  61.     gave useful suggestions. Needless to say that all remaining errors
  62.     are mine.
  63.     Arjen is author of BOOTCOMP.zip: a package which uses the original
  64.     BIOS interrupts to detect ANY changes to the bootsector [possibly]
  65.     made by a virus. He also wrote ACD (ChDir FAST; more features than
  66.     LCD/NCD and free).
  67.  
  68.  
  69.     2. How to execute PATCH22.
  70.     ___________________________________________________________________
  71.  
  72.     PATCH22 can accept patches on the command line or from a file.
  73.  
  74.  
  75.     2.1 Command line patch.
  76.     _______________________
  77.  
  78.     form:   PATCH22 fname patch
  79.     fname   - file to be patched
  80.     patch   - patch command: +##*##si?search_text?new_text?
  81.  
  82.     If the patch line on the command line contains spaces, it must be
  83.     enclosed in double quotes.
  84.  
  85.     examples:
  86.     PATCH22 test.exe ?abc?cde?         replace (with confirmation)
  87.                                        every occurrence of abc with cde.
  88.     PATCH22 test.exe "?a c?c e?"       replace (with confirmation)
  89.                                        every occurrence of a c with c e.
  90.  
  91.     If in the last example the double quotes are omitted, PATCH22 will
  92.     think that the patch is ?a, and tell you that it expects a ?.
  93.  
  94.     2.2 Command file patch.
  95.     _______________________
  96.  
  97.     form:   PATCH22 @fname
  98.     @fname  - file with (multiple) PATCH22 commands, with format:
  99.               fname  +##*##si?Search_text?New_text?
  100.  
  101.     If the patch command is in a file, line breaks in the Search_text
  102.     and New_text are ignored.
  103.  
  104.     example:
  105.  
  106.         PATCH22 @test.p22
  107.  
  108.     where test.p22 looks like:
  109.         ; comment lines start with a semi colon.
  110.         test.exe ?a c?c e?
  111.         ; line breaks in the Search_text and New_text are ignored:
  112.         test.exe ?a cdd?c edd?
  113.         ; equals
  114.         test.exe ?a cd
  115.         d?c ed
  116.         d?
  117.         ; note that no double quotes are used here.
  118.  
  119.  
  120.     3. The patch command.
  121.     ___________________________________________________________________
  122.  
  123.     form:    +##*##si?Search_text?New_text?"
  124.     syntax:  patch = Conditions "?" Search_text "?" New_text "?".
  125.  
  126.     The syntax reads as follows:
  127.     "a"    indicates a literal text a.
  128.     [b]    indicates an optional item b.
  129.     {c}    indicates one or more occurences of c.
  130.     d|e    indicates either d or e.
  131.  
  132.     3.1 The Conditions.
  133.  
  134.     syntax: Conditions     = [Offset][Max_#_patches][Silent_mode].
  135.               Offset       = ["+"] long | "-" long.
  136.               Max_#_patches= "*" int.
  137.                 long       = ["0"] ["x" | "X"] digit {digit}.
  138.                 int        = ["0"] ["x" | "X"] digit {digit}.
  139.               Silent_mode  = "s".
  140.               Ignore_case  = "i".
  141.  
  142.     The Offset is a signed long integer, while the maximum number of patches
  143.     is a * followed by an unsigned integer. These integers can be decimal,
  144.     hexadecimal (leading 0x or 0X) or octal (leading 0).
  145.     An s indicates silent mode. Each number is read up to the first character
  146.     which is not part of it.
  147.     An i indicates case insensitive searching. The search string is converted
  148.     to uppercase, so comparosion is mad in uppercase. The default is case
  149.     sensitivity.
  150.     The Conditions field can be empty, in which case the Offset is zero,
  151.     every patch has to be confirmed, and there is no maximum number of
  152.     patches.
  153.  
  154.     examples: 0x131d       Offset is 131d (hexadecimal), no maximum
  155.                            number of patches.
  156.               +0177*12     Offset is 177 (octal), not more than 12 patches.
  157.               +177*12      Offset is 177 (decimal), not more than 12 patches.
  158.               *1s          Zero Offset, one patch, silent mode (no prompt for
  159.                            confirmation of patch).
  160.               *09?n?n?     The 0 in the Max_#_patches field indicates an octal
  161.                            number, but 9 is not octal, so scanning stops and
  162.                            a 0 is read. The 9 then is interpreted as the
  163.                            Offset. However a request of 0 patches generates
  164.                            an error message.
  165.  
  166.     3.2 The Search_text and New_text.
  167.     _________________________________
  168.  
  169.     syntax: Search_text    = [ {chars | escape_code} ].
  170.               escape_code  = "\a" | "\b" | "\f" | "\n" | "\r" | "\t" | "\v"
  171.                            | "\\" | "\?" | "\'" | "\""
  172.                            | "\" octal [octal [octal]]
  173.                            | "\x" hex [hex]
  174.                            | "\w" hex [hex [hex [hex]]]
  175.                            | "\h" hex hex {hex hex}.
  176.             New_text       = Search_text.
  177.  
  178.     The text is a C-type character constant. It may contain the C
  179.     escape codes
  180.     \a (07h), \b (08h), \f (0Ch), \n (0Ah), \r (0Dh), \t (09h), \v (0Bh);
  181.     or
  182.     \###   (octal byte, not more than 3 digits);
  183.     \x##   (hexadecimal byte, not more than 2 digits).
  184.     \w#### (hexadecimal word, not more than 4 digits).
  185.     The characters \ ? ' " must be written as: \" \\ \? \' \".
  186.     An additional escape code is \h, which indicates that the rest of the
  187.     text (up to the question mark which indicates the end) consists
  188.     of two-digit hexadecimal numbers.
  189.  
  190.     examples: \h0d0a00       three hexadecimal numbers:
  191.                              carriage return, line feed, null character.
  192.               \r\n\0         the same three characters, in escape codes,
  193.                              (note that \0 is an octal number).
  194.               «gr_»          literal text.
  195.               \x1\xa\wb000   two bytes and one word: 01h 0Ah B000h
  196.                              (since on IBM PC's low order byte comes before
  197.                              hi order byte this is written as 01h 0Ah 00h B0h)
  198.  
  199.     3.3 How the patch is executed.
  200.     ______________________________
  201.  
  202.     Assume non-silent mode (default).
  203.  
  204.     First PATCH22 locates the search string. If the search string is
  205.     empty, the first byte in the file matches. Then PATCH22 displays
  206.     the search string.
  207.  
  208.     Next it moves the file pointer Offset bytes from the start of the
  209.     found search string. (If the Offset is negative, PATCH22 will move
  210.     backwards.)
  211.     Then it will display the context with the bytes selected for modi-
  212.     fication highlighted. PATCH22 will also display the new text, and
  213.     prompt for confirmation of the patch.
  214.  
  215.     The file will be unchanged in size, unless the patch extends beyond
  216.     the current end of the file. The time and date stamp of the file are
  217.     updated.
  218.  
  219.     Example 1: replace a tex